package org.melanesia.converters;

import java.sql.Statement;

import org.melanesia.converters.exceptions.ConversionException;

/**
 * JavaToJdbcConverter is a base class for implementation of converters from
 * java to jdbc type. This converters are used in the process of mapping Java
 * objects to jdbc statement in/out parameters. Note, that every object passed
 * as the parameter is required to have a JavaToJdbcConverter that will convert
 * its value into an appropriate jdbc type.
 *
 * @see org.melanesia.converters.TypeConverter#registerConverter(Class, JavaToJdbcConverter)
 *
 * @author marcin.kielar
 */
public abstract class JavaToJdbcConverter {

    /**
     * Returns JDBC Type that should be used with converted value.
     *
     * @see java.sql.Types
     * @param converterContext
     *            Reference to {@link org.melanesia.converters.TypeConverter}
     *
     * @return JDBC Type
     */
	public abstract int getJdbcType(TypeConverter converterContext);

    /**
     * Returns the name of the user-defined database type.
     * This method should usually return null, as JDBC drivers usually are able
     * to determine database type name using only the jdbc type. However,
     * this is not the case with user-defined database types, and in such cases
     * explicitly passed name of the database type is required.
     *
     * Value containing the name of the user-defined database type should be returned when converting into such a type.
     * There is no need of returning database names for types like VARCHAR, NUMERIC, DATE etc.
     *
     * @param converterContext Reference to {@link org.melanesia.converters.TypeConverter}
     * @return name of the user-defined database type
     */
	public String getDatabaseTypeName(final TypeConverter converterContext) {
	    return null;
	}

    /**
     * Converts value into a form that is applicable to CallableStatememt
     * object.
     *
     * @param converterContext
     *            Reference to {@link org.melanesia.converters.TypeConverter}
     * @param value
     *            value to convert
     * @param stmt
     *            instance of Statement that this value is passed to
     * @param parameterName
     *            name of the parameter that this value is associated with
     * @return converted value
     * @throws ConversionException
     *            when conversion fails
     */
    public abstract Object convert(TypeConverter converterContext, Object value, Statement stmt, String parameterName)
            throws ConversionException;
}
